<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools 1.3 Documentation - Locale/Locale</title>
</head>

<body>
  <div class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Locale">Locale</a></h4>
      <div class="menu-item"><a href="#"></a></div>
      <div class="menu-item"><a href="#Locale:onChange">onChange</a></div>
      <div class="menu-item"><a href="#Locale:define">define</a></div>
      <div class="menu-item"><a href="#Locale:use">use</a></div>
      <div class="menu-item"><a href="#Locale:getCurrent">getCurrent</a></div>
      <div class="menu-item"><a href="#Locale:get">get</a></div>
      <div class="menu-item"><a href="#Locale:inherit">inherit</a></div>
      <div class="menu-item"><a href="#Locale:list">list</a></div>
    </div>
    <div class="l-border r-border span-15 content">
      <h1 id="Locale"><a href="#Locale">Class Instance: Locale</a></h1>
      <p class="description">Contains methods and data necessary to provide localization.</p>
      <h3>Notes</h3>
      <ul>
        <li>The locale sets are protected in a private variable that can only be altered using methods in <em>Locale</em> documented below. Though you can retrieve locale sets, which are objects, you should not alter these through assignment but instead use the <em>.define</em> method.</li>
        <li>Locale sets can contain any type of object, so, for instance, a language item could be an <em>array</em>, a <em>function</em>, a <em>string</em>, or even another <em>class</em>. Classes that make use of these items must be aware of the types of objects in the language file.</li>
        <li>Language items that are functions are executed and their results are returned. So if you execute <em>Locale.get('Date.ordinal', 4)</em>, then the ordinal member will be executed and passed <em>4</em> as its argument. If <em>ordinal</em> is not a function, then its value will simply be returned.</li>
        <li>Users are encouraged to send in updates and additions to the MooTools team to help us grow this collection of translations.</li>
      </ul>
      <h2><a href="#">Example language file</a></h2>
      <p class="description">Below is an example language file from <em>Locale.en-US.Date.js</em>. Note that some members are
        arrays (months and days), others are strings, and one is even a function. Also note that
        some of the strings contain notation for variable substitution. Each class establishes it's
        own conventions for the language file that is required and is therefor required to document
        those conventions. Look for these at the bottom of the class's Locale documentation.</p>
      <pre class="javascript">Locale.<span class="me1">define</span><span class="br0">(</span><span class="st0">'en-US'</span>, <span class="st0">'Date'</span>, <span class="br0">{</span>

&nbsp;
    months: <span class="br0">[</span><span class="st0">'January'</span>, <span class="st0">'February'</span>, <span class="st0">'March'</span>, <span class="st0">'April'</span>, <span class="st0">'May'</span>, <span class="st0">'June'</span>, <span class="st0">'July'</span>, <span class="st0">'August'</span>, <span class="st0">'September'</span>, <span class="st0">'October'</span>, <span class="st0">'November'</span>, <span class="st0">'December'</span><span class="br0">]</span>,
    days: <span class="br0">[</span><span class="st0">'Sunday'</span>, <span class="st0">'Monday'</span>, <span class="st0">'Tuesday'</span>, <span class="st0">'Wednesday'</span>, <span class="st0">'Thursday'</span>, <span class="st0">'Friday'</span>, <span class="st0">'Saturday'</span><span class="br0">]</span>,
    dateOrder: <span class="br0">[</span><span class="st0">'month'</span>, <span class="st0">'date'</span>, <span class="st0">'year'</span>, <span class="st0">'/'</span><span class="br0">]</span>,
    AM: <span class="st0">"AM"</span>,
    PM: <span class="st0">"PM"</span>,
    <span class="co1">//members can be functions; these will be executed and passed any arguments with .get(member[,args])</span>

    ordinal: <span class="kw2">function</span><span class="br0">(</span>dayOfMonth<span class="br0">)</span><span class="br0">{</span>
        <span class="kw1">return</span> <span class="br0">(</span>dayOfMonth &gt; <span class="nu0">3</span> &amp;&amp; dayOfMonth &lt; <span class="nu0">21</span><span class="br0">)</span> ? <span class="st0">'th'</span> : <span class="br0">[</span><span class="st0">'th'</span>, <span class="st0">'st'</span>, <span class="st0">'nd'</span>, <span class="st0">'rd'</span>, <span class="st0">'th'</span><span class="br0">]</span><span class="br0">[</span>Math.<span class="me1">min</span><span class="br0">(</span>dayOfMonth % <span class="nu0">10</span>, <span class="nu0">4</span><span class="br0">)</span><span class="br0">]</span>;
    <span class="br0">}</span>,
    lessThanMinuteAgo: <span class="st0">'less than a minute ago'</span>

&nbsp;
<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h2 id="Locale:onChange"><a href="#Locale:onChange">Locale event: onChange</a></h2>
      <p class="description">This event is fired whenever the current locale is changed for the user (for instance,
        from "en-US" to "es-ES") or whenever the current selected locale is updated with new data.</p>
      <h3>Example:</h3>
      <pre class="javascript">Locale.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'change'</span>, <span class="kw2">function</span><span class="br0">(</span><span class="kw3">name</span><span class="br0">)</span><span class="br0">{</span>

    <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'Youre locale settings changed to '</span> + <span class="kw3">name</span><span class="br0">)</span>;
<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h2 id="Locale:define"><a href="#Locale:define">Locale method: define</a></h2>
      <p class="description">Defines properties for a given set in a given language.</p>
      <h3>Syntax</h3>
      <pre class="javascript">Locale.<span class="me1">define</span><span class="br0">(</span><span class="kw3">name</span>, set, data<span class="br0">)</span>;
<span class="co1">// or</span>
Locale.<span class="me1">define</span><span class="br0">(</span><span class="kw3">name</span>, set, key, value<span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>name - (<em>string</em>) the locale name you want to alter.</li>
        <li>set - (<em>string</em>) the set you want to alter in that locale.</li>
        <li>data - (<em>object</em>) the key/values object for the set and locale.</li>
        <li>key - (<em>string</em>) the key of a property for the data object for the set and locale.</li>
        <li>value - (<em>mixed</em>) the value of a property for the data object for the set and locale.</li>
      </ol>
      <h3>Example</h3>
      <pre class="javascript">Locale.<span class="me1">define</span><span class="br0">(</span><span class="st0">'en-US'</span>, <span class="st0">'Date'</span>, <span class="br0">{</span>

    months: <span class="br0">[</span><span class="st0">'January'</span>, <span class="st0">'February'</span>, <span class="st0">'March'</span>, <span class="st0">'April'</span>, <span class="st0">'May'</span>, <span class="st0">'June'</span>, <span class="st0">'July'</span>, <span class="st0">'August'</span>, <span class="st0">'September'</span>, <span class="st0">'October'</span>, <span class="st0">'November'</span>, <span class="st0">'December'</span><span class="br0">]</span>,
    days: <span class="br0">[</span><span class="st0">'Sunday'</span>, <span class="st0">'Monday'</span>, <span class="st0">'Tuesday'</span>, <span class="st0">'Wednesday'</span>, <span class="st0">'Thursday'</span>, <span class="st0">'Friday'</span>, <span class="st0">'Saturday'</span><span class="br0">]</span>,
    dateOrder: <span class="br0">[</span><span class="st0">'month'</span>, <span class="st0">'date'</span>, <span class="st0">'year'</span>, <span class="st0">'/'</span><span class="br0">]</span>,
    AM: <span class="st0">"AM"</span>,
    PM: <span class="st0">"PM"</span>

<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h3>Returns</h3>
      <ul>
        <li> <em>object</em> - Locale Set instance</li>
      </ul>
      <h2 id="Locale:use"><a href="#Locale:use">Locale method: use</a></h2>
      <p class="description">Sets the current locale for the user.</p>
      <h3>Syntax</h3>
      <pre class="javascript">Locale.<span class="kw2">use</span><span class="br0">(</span><span class="kw3">name</span><span class="br0">)</span>;
</pre>
      <h3>Arguments</h3>
      <ol>
        <li>name - (<em>string</em>) the new locale name to use.</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li> <em>object</em> - Locale (the instance)</li>
      </ul>
      <h3>Example</h3>
      <pre class="javascript">Locale.<span class="kw2">use</span><span class="br0">(</span><span class="st0">'nl-NL'</span><span class="br0">)</span>;
</pre>
      <h2 id="Locale:getCurrent"><a href="#Locale:getCurrent">Locale method: getCurrent</a></h2>
      <p class="description">Returns the locale name currently in use.</p>
      <h3>Syntax</h3>
      <pre class="javascript">Locale.<span class="me1">getCurrent</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>Returns</h3>
      <ul>
        <li> <em>string</em> - the locale name (i.e. "en-US").</li>
      </ul>
      <h2 id="Locale:get"><a href="#Locale:get">Locale method: get</a></h2>
      <p class="description">Retrieves a set of locale properties for the current language or the whole set.</p>
      <h3>Syntax</h3>
      <pre class="javascript">Locale.<span class="me1">get</span><span class="br0">(</span>key<span class="br0">[</span>, args<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>key - (<em>string</em>: optional) The member you wish to retrieve. This should look like <code>Set.key</code>. This will use <a href="../../../docs/more/Types/Object.Extras.html#Object:Object-getFromPath">Object.getFromPath</a> for nested properties.</li>
        <li>args - (<em>mixed</em>: optional) A single value or an array of values that are passed to the language value (if it is not a function, these are ignored; if it is a function, these are passed);</li>
      </ol>
      <h3>Example</h3>
      <pre class="javascript">Locale.<span class="me1">get</span><span class="br0">(</span><span class="st0">'Date.dayAgo'</span><span class="br0">)</span>; <span class="co1">//"1 day ago"</span>
Locale.<span class="me1">get</span><span class="br0">(</span><span class="st0">'Date.nested.property'</span><span class="br0">)</span>; <span class="co1">// the get method is using Object.getFromPath to find properties</span>

Locale.<span class="me1">get</span><span class="br0">(</span><span class="st0">'Date.ordinal'</span>, <span class="nu0">1</span><span class="br0">)</span>; <span class="co1">//"st" &gt; as in "1st"</span>
Locale.<span class="me1">get</span><span class="br0">(</span><span class="st0">'Date.dayAgo'</span>, <span class="st0">'foo'</span><span class="br0">)</span>; <span class="co1">//foo is ignored</span>

Locale.<span class="me1">get</span><span class="br0">(</span><span class="st0">'Date'</span><span class="br0">)</span>; <span class="co1">//returns the object of key/values for Date in the current language</span>
</pre>
      <h3>Returns</h3>
      <ul>
        <li>If passed a valid set and key, returns the locale value for the given set (usually a string).</li>
        <li>If passed a valid set and no key, returns an object containing all the key/values in the translation.</li>
        <li>If passed a valid set, key, and arguments, passes the arguments to the value if it is a function and returns what it returns, otherwise returns the value.</li>
      </ul>
      <h3>Notes:</h3>
      <ol>
        <li>Dots '<code>.</code>' in the key argument can be used to find nested properties.</li>
      </ol>
      <h2 id="Locale:inherit"><a href="#Locale:inherit">Locale method: inherit</a></h2>
      <p class="description">It often occurs that localization data is based on another language.
        For example Spanish in Argentina has many similarities with Spanish
        or Number formatting in Europe is the same for lots of Europe countries.
        Therefore it is possible to inherit another locale data from another
        language. <code>Locale.get</code> will search trough the inherited locale names
        until a property is set.</p>
      <h3>Syntax:</h3>
      <pre class="javascript">Locale.<span class="me1">inherit</span><span class="br0">(</span><span class="kw3">name</span>, parent<span class="br0">[</span>, set<span class="br0">]</span><span class="br0">)</span>;
</pre>
      <h3>Arguments:</h3>
      <ol>
        <li>name - (<em>string</em>) The locale name</li>
        <li>parent - (<em>string</em>) The locale name to inherit from</li>
        <li>set - (<em>string</em>, optional) If the locale data should only inherit for specific data sets, set this argument</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li> <em>object</em> - Locale (the instance)</li>
      </ul>
      <h3>Example:</h3>
      <pre class="javascript">Locale.<span class="me1">inherit</span><span class="br0">(</span><span class="st0">'es-AR'</span>, <span class="st0">'es-ES'</span><span class="br0">)</span>;

&nbsp;
<span class="co1">// Only inherit for a specific data set</span>
Locale.<span class="me1">inherit</span><span class="br0">(</span><span class="st0">'de-CH'</span>, <span class="st0">'de-DE'</span>, <span class="st0">'Number'</span><span class="br0">)</span>;
</pre>
      <h2 id="Locale:list"><a href="#Locale:list">Locale method: list</a></h2>
      <p class="description">Returns an array of languages currently supported.</p>
      <h3>Syntax</h3>
      <pre class="javascript">Locale.<span class="me1">list</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>Returns</h3>
      <ul>
        <li> <em>array</em> an array of locale names (<em>strings</em>)</li>
      </ul>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
